TKey Random Number Generator

Description

The TKey Random Number Generator app allows a user and a client system to get high-quality random numbers from a source separate from the client. A unique feature is that it can sign the random data delivered, thus allowing the user to verify the integrity of the generator, the integrity of the data, and the origin of the data delivered.

Secure Random Number Generators

The TKey Secure Random Number Generator app is influenced by the Hash_DRBG random number generator specified by NIST in SP 800-90A. The Hash_DRBG is what NIST refers to as a deterministic random bit generator (DBRG), basically an algorithm that, given a seed state, will generate a sequence of numbers while updating its internal state. Outside of NIST, these types of algorithms are called pseudorandom number generators (PRNGs) and, for security-related use cases, cryptographically secure pseudo random number generators (CSPRNG).

An important aspect of a CSPRNG is that there is an internal, secret state that is used to generate the output. But observing the generated output does not aid an attacker in being able to guess previous or future outputs. The state may also be reseeded to add new entropy (i.e., random noise collected from a physical source) to make it harder for an attacker to guess the internal state.

The Hash_DRBG is built around a cryptographically secure hash function, in this case the BLAKE2s. The internal state is hashed. Parts of the resulting digest are presented as output. The digest, combined with internal counters, is used to update the internal state.

The NIST Hash_DRBG standard is quite complex, with requirements on functions to instantiate or remove a generator, mechanisms to set and check security levels, etc. For the TKey application, these functions do not really make sense, and we chose not to implement all of the required functionality according to the standard. This is why we say that the generator is influenced by, not an implementation of, the NIST Hash_DRBG.

Installation and usage Linux →
Installation and usage macOS →

Installation and usage

Linux

Download and install

We provide an deb package for Debian based distributions, such as Ubuntu. If you run a different Linux distribution, you may download the source code from or GitHub repository, compile and install.

The app is statically linked has been tested on Ubuntu 22.10 and Debian 12. You can choose between amd64 or arm64.
As an alternative it is also possible to compile and install directly from source code.

Open a terminal

downloading the deb package
For amd64

wget https://github.com/tillitis/tkey-random-generator/releases/download/v0.0.2/tkey-random-generator_0.0.2-1_amd64.deb

For arm64

wget https://github.com/tillitis/tkey-random-generator/releases/download/v0.0.2/tkey-random-generator_0.0.2-1_arm64.deb

Install tkey-random-generator
For amd64:

sudo dpkg -i tkey-random-generator_0.0.2-1_amd64.deb

For arm64

sudo dpkg -i tkey-random-generator_0.0.2-1_arm64.deb

tkey-random-generator is now installed and accessible in your path

Usage

You can now run

tkey-random-generator --help

The app have 2 sub-commands, “generate” and “verify”. Continue reading or use the man page for more info

man tkey-random-generator

Generating signed random data

To generate 256 bytes of random data, signed, in binary format, to the file “binary_output” use

tkey-random-generator generate 256 --signature --file binary_output

This will produce the output (with different Public key, signature and hash)

Auto-detected serial port /dev/ttyACM0
Connecting to device on serial port /dev/ttyACM0...
Writing 256 B of random data to: binary_output

Public key: e468d678a5acca20131c15685887a004cb92e5e679d7bce9ee128018e3040dcb
Signature: 16cc51227f4833ba29bf2abab096c0dd32910841bedb7d919f2573c58569d10c54cfe91b980ac0bc04ed4c0baa7722f7245bc6a4cf49792152b472118c4d0b08
Hash: 91698c7b01868e6b29b3a27faff4d8af8ea71eb56ddef48078ab34ebff32b586

Verifying signature ...
signature verified.

Full usage of “generate” command

Usage ./tkey-random-generator generate  [-s] [--uss] [flags..]

  Generates amount of data specified with  and optionally create a signature
  to make it possible to provide proof of the origin. The generated random data is
  first hashed using BLAKE2s, and then signed with and Ed25519 private key.

  Output can be chosen between stdout (hex) and a binary file.

  Usage:

  -p, --port PATH       Set serial port device PATH. If this is not
                        passed, auto-detection will be attempted.
      --speed BPS       Set serial port speed in BPS (bits per second).
                        (default 62500)
  -s, --signature       Get the signature of the generated random data.
  -f, --file FILE       Output random data as binary to FILE.
  -h, --help            Output this help.
      --uss             Enable typing of a phrase to be hashed as the User
                        Supplied Secret. The USS is loaded onto the TKey
                        along with the app itself. A different USS results
                        in different Compound Device Identifier, different
                        start of the random sequence, and another key pair
                        used for signing.
      --uss-file FILE   Read FILE and hash its contents as the USS. Use
                        '-' (dash) to read from stdin. The full contents
                        are hashed unmodified (e.g. newlines are not stripped).
  -v, --verbose         Be more verbose

Verifying signature of signed random data

To verify a signature over previously generated random data you need the random data, the signature and the public key – each in a separate file – from the TKey it was generated on. Note that you do not need a TKey connected to verify.

Then run

tkey-random-generator verify random_data_file signature_file public_key_file

If the “random_data_file” is in binary format, use the “–binary” flag.

This would produce the output (using the example above)

Verifying signature ...
Public key: e468d678a5acca20131c15685887a004cb92e5e679d7bce9ee128018e3040dcb
Signature: 16cc51227f4833ba29bf2abab096c0dd32910841bedb7d919f2573c58569d10c54cfe91b980ac0bc04ed4c0baa7722f7245bc6a4cf49792152b472118c4d0b08
BLAKE2s hash: 91698c7b01868e6b29b3a27faff4d8af8ea71eb56ddef48078ab34ebff32b586
Signature verified.

Full usage of the “verify” command

Usage: ./tkey-random-generator verify FILE SIG-FILE PUBKEY-FILE [-b]

Verifies whether the Ed25519 signature of the message is valid.
Does not need a connected TKey to verify.

First the message, FILE, is hashed using BLAKE2s, then the signature
is verified with the message and the public key.

FILE is either a binary or a hex representation of the random data.
SIG-FILE is expected to be an 64 bytes Ed25519 signature in hex.
PUBKEY-FILE is expected to be an 32 bytes Ed25519 public key in hex.

The return value is 0 if the signature is valid, otherwise non-zero.
Newlines will be striped from the input files.

-b, --binary      Specify if the input FILE is in binary format.
-h, --help        Output this help.

macOS